🔍 API de Consultas - Documentação Completa

📋 Visão Geral

A API de Consultas é responsável por fornecer consultas estruturadas e otimizadas para diferentes aspectos do sistema CordenaAi, incluindo hierarquia organizacional (instituições, unidades, turmas), informações completas de usuários com suas funções, e relacionamentos entre responsáveis e atletas. Esta API fornece dados agregados e relacionamentos complexos de forma eficiente, facilitando a construção de dashboards, relatórios e interfaces administrativas.

🎯 Endpoints Disponíveis

🔍 Consultas - Consultas Estruturadas do Sistema

1. GET /api/Consultas/instituicoes-com-unidades

Obter Instituições com Unidades

2. GET /api/Consultas/unidades-com-turmas

Obter Unidades com Turmas

3. GET /api/Consultas/turmas/{turmaId}/completa

Obter Turma Completa

4. GET /api/Consultas/usuarios-com-funcoes

Obter Usuários com Funções

5. GET /api/Consultas/usuarios/{identificador}/completo

Obter Usuário Completo

6. GET /api/Consultas/responsaveis-com-atletas

Obter Responsáveis com Atletas

🔧 Modelo de Dados

Estrutura de Instituição Completa

{
  "id": "integer",
  "descricao": "string",
  "local": "string",
  "tipo": "TipoInstituicao",
  "unidades": [
    {
      "id": "integer",
      "nome": "string",
      "local": "string",
      "tipo": "TipoUnidade",
      "quantidadeTurmas": "integer"
    }
  ],
  "dataCadastro": "datetime",
  "dataAtualizacao": "datetime"
}

Estrutura de Unidade Completa

{
  "id": "integer",
  "nome": "string",
  "local": "string",
  "tipo": "TipoUnidade",
  "instituicao": {
    "id": "integer",
    "descricao": "string",
    "local": "string"
  },
  "turmas": [
    {
      "id": "integer",
      "nome": "string",
      "status": "StatusTurma",
      "responsavelId": "string",
      "responsavelNome": "string"
    }
  ],
  "dataCadastro": "datetime",
  "dataAtualizacao": "datetime"
}

Estrutura de Turma Completa

{
  "id": "integer",
  "nome": "string",
  "status": "StatusTurma",
  "unidade": {
    "id": "integer",
    "nome": "string",
    "local": "string",
    "tipo": "TipoUnidade"
  },
  "professor": {
    "id": "string",
    "nome": "string",
    "nomeSocial": "string",
    "email": "string",
    "userName": "string"
  },
  "alunos": [
    {
      "id": "string",
      "nome": "string",
      "nomeSocial": "string",
      "email": "string",
      "userName": "string",
      "papelNaTurma": "PapelNaTurma"
    }
  ],
  "dataCadastro": "datetime",
  "dataAtualizacao": "datetime"
}

Estrutura de Usuário Completo

{
  "id": "string",
  "userName": "string",
  "nome": "string",
  "nomeSocial": "string",
  "email": "string",
  "cpf": "string",
  "celular": "string",
  "dataNascimento": "datetime",
  "genero": "string",
  "status": "boolean",
  "funcoes": [
    {
      "tipo": "string",
      "relacao": "string",
      "usuarioRelacionado": "string",
      "turma": "string",
      "dataCadastro": "datetime"
    }
  ],
  "dataCadastro": "datetime",
  "dataAtualizacao": "datetime"
}

Estrutura de Responsável Completo

{
  "id": "string",
  "nome": "string",
  "email": "string",
  "userName": "string",
  "status": "boolean",
  "atletas": [
    {
      "id": "string",
      "nome": "string",
      "relacao": "string",
      "dataCadastro": "datetime"
    }
  ],
  "funcoes": [
    {
      "tipo": "string",
      "relacao": "string",
      "turma": "string",
      "dataCadastro": "datetime"
    }
  ]
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

📊 Casos de Uso Principais

1. Dashboard Administrativo

GET /api/Consultas/instituicoes-com-unidades
Authorization: Bearer {token}

2. Gestão de Unidades

GET /api/Consultas/unidades-com-turmas
Authorization: Bearer {token}

3. Visualização de Turma

GET /api/Consultas/turmas/123/completa
Authorization: Bearer {token}

4. Relatório de Usuários

GET /api/Consultas/usuarios-com-funcoes
Authorization: Bearer {token}

5. Perfil de Usuário

GET /api/Consultas/usuarios/[email protected]/completo
Authorization: Bearer {token}

6. Gestão de Responsáveis

GET /api/Consultas/responsaveis-com-atletas
Authorization: Bearer {token}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

Regras de Negócio

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

Otimizações

🔄 Integração com Outros Módulos

Módulos Relacionados

📱 Uso em Aplicações

Web App

Mobile App

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

📚 Exemplos Práticos

Fluxo de Consulta Hierárquica

  1. GET /api/Consultas/instituicoes-com-unidades para estrutura geral
  2. GET /api/Consultas/unidades-com-turmas para detalhes de unidades
  3. GET /api/Consultas/turmas/{id}/completa para turma específica

Fluxo de Consulta de Usuário

  1. GET /api/Consultas/usuarios/{identificador}/completo para dados do usuário
  2. Verificação de funções e relacionamentos
  3. Exibição de informações completas

Fluxo de Gestão de Responsáveis

  1. GET /api/Consultas/responsaveis-com-atletas para lista de responsáveis
  2. Visualização de atletas vinculados
  3. Gestão de relacionamentos

🎯 Tipos e Enums

TipoInstituicao

TipoUnidade

StatusTurma

PapelNaTurma

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi